Introduction
The Assetic REST API allows data to be bulk exported from Assetic utilising saved profiles from the Advanced Search functionality.
There are 2 REST API endpoints:
- GET /api/v2/search
- GET /api/v2/search/GeoJson
The difference between the 2 endpoints is that the API endpoint GET /api/v2/search/GeoJson returns the spatial location of each record, and the whole search result is formatted as GeoJson to allow GIS applications to utilise the search result.
Advanced Search Profiles
The first step is to save an Advanced Search Profile. This is described in Search Basics. Configure an Advanced Search Profile that returns the required fields, including any filters that you may require to restrict the search results.
The API endpoints require the unique GUID identifier of the Advanced Search Profile. To obtain this identifier simply open the Advanced Search Profile in Assetic and copy the GUID part from the URL in the browser navigation bar. In the example screenshot below the full URL is: https://xxx.assetic.net/Search/AdvancedSearchProfile/SPDashboard/Default/ff03c4bd-4f1d-e611-9458-06edd62954d7?loadprofile=True
From this URL the GUID is: ff03c4bd-4f1d-e611-9458-06edd62954d7
Tiles
Tiles are used on dashboards for grids and charts. The tile may be used as the basis of a search. Note that the GUID of the tile is not displayed on the application and requires some technical skill to obtain.
Using the API
The API endpoints have the following parameters (common to both endpoints):
| Parameter | Description | Type | Mandatory |
| requestParams.id | The GUID identifier for the Advanced Search Profile | GUID | Conditional |
| requestParams.sourceTileId | The GUID of a system tile | GUID | Conditional |
| requestParams.page | The page number to retrieve. Default=1 | Integer | No |
| requestParams.pagesize | The number of records to retrieve per page. Default = 20, Maximum=500 | Integer | No |
| requestparams.sorts | Apply a sort order to the results | String | No |
| requestParams.filters | Filter the results | String | No |
Page Number and Page Size
Setting page size (requestParams.pagesize) limits the number of records returned per request. Where there are more results than specified by page size then subsequent requests can be made to the API endpoint to get the full result set. For each subsequent request the page number (requestParams.page) specified in the parameters should be increased by 1. The API endpoint response includes 'Total Results' which is the number of records the .
Filters
The search results may be filtered by fields in the search.
The filter format currently supports:
- 'Equals' which is represented by '='
- 'Less Than' which is represented by '<'
- 'Less Than or Equal To' which is represented by '<='
- 'Greater Than' which is represented by '>'
- 'Greater Than or Equal To' which is represented by '>='
As an example, to filter by Asset Type='Sealed Road' the filter is:
requestParams.filters=ComplexAssetType=Sealed Road
To get the field name to filter by, first run the search end point /api/v2/search/{id}/metadata, where {id} is the guid of the search profile. The response body is a list of field mappings that map the display name visible in Assetic with the internal field name to be used in the filter, and the data type of the field.
{ "TotalResults": 2, "TotalPages": 1, "Page": 1, "ResourceList": [ { "Label": "Asset Asset Catalogue", "Name": "ComplexAssetAssetCatalogue", "Type": "System.String", "_links": [], "_embedded": null }, { "Label": "Asset Category", "Name": "ComplexAssetAssetCategory", "Type": "System.String", "_links": [], "_embedded": null } ] }
Dates have the format YYYY-MM-DDThh:mm:ss where:
- YYYY represents a 4 digit year
- MM represents the month as a number
- DD represents the day
- T indicates the time follows the date. Time is optional. If only using date then exclude the 'T' and what follows the 'T'
- hh represents hours on 24hour clock
- mm represents minutes
- ss represents seconds
The following example shows a filter that filters by Last Modified Date greater or equal to 4th July 2016
ComplexAssetLastModified>=2016-07-04
A filter may include several filters, each separated by a comma. When using multiple filters each filter is joined as an 'And', so only records that satisfy all filters will be returned.
In the example below only records where the Asset Type='Sealed Road' that were modified on or after 4th July 2016 will be returned
ComplexAssetLastModified>=2016-07-03T1:16:07,ComplexAssetType=Sealed Road
Sorting
The results may also be ordered via requestparams.sorts.
The syntax is to apply the keyword 'asc' (Ascending order) or 'desc' (Descending order) to the field name, delimited by a dash ('-')
The following example shows the syntax for ordering the results by Asset ID in Ascending order
ComplexAssetId-asc
The following example shows the syntax for ordering the results by Asset ID in Descending order
ComplexAssetId-desc
Sample Request
The following request is used to return 500 records from the first page.
https://[your_site].assetic.net/api/v2/search?requestParams.id={profile_guid}&requestParams.page=1&requestParams.pageSize=500
The GeoJson equivalent is:
https://[your_site].assetic.net/api/v2/search?requestParams.id={profile_guid}&requestParams.page=1&requestParams.pageSize=500
For a sample script which performs the bulk export via API, please visit this article on the Integration SDK page.
